Basic setup to use nkScripts

Create an environment

First thing to do when dealing with nkScripts is creating an Environment. The Environment is an isolated space where variables, types, functions, can be declared and used. You can have as many environments as you want. All of them will have their own state, which means that setting a variable within one environment won't impact the other ones.

Setting up an environment goes through the creation and basic setup of it. First, we need to include :

#include <NilkinsScripts/Environments/Environment.h> #include <NilkinsScripts/Environments/EnvironmentManager.h> #include <NilkinsScripts/Interpreters/Interpreter.h>

And then, let's use that to setup an environment :

nkScripts::Environment* env = nkScripts::EnvironmentManager::getInstance()->createOrRetrieve("firstEnv") ; env->setEnvironmentFor(nkScripts::INTERPRETER::LUA) ;

If you manipulated other components already, you will be familiar with the process of creating resources within the components. Request the Manager, which is a Singleton, to create or retrieve the resource for you. If the resource exists, the existing one will be returned. Else, a new one will be created. As a result, here we are creating a new environment that we will identify through the name "firstEnv". The manager then returns the pointer over this resource. Note that the manager owns the memory returned, you will never have to delete it manually. For such purpose, you need to erase it through the manager, or keep it until the application shutdown, in which case the manager cleans the memory by itself.

Next step is to setup our resource. For our basic need here, we only need to prepare the environment to work with a scripting language. At the moment, only Lua is available, so let's go with it ! By calling the setEnvironmentFor method, ou environment is reset to a basic state, ready to cope with scripts written for Lua.

And with this, our environment is already good to go. We have a basic Lua environment with default scripting capabilities. Let's see how we can dialog with it !

Creating a script

To talk to environments, we needs scripts. In nkScripts, Scripts are objects which hold the sources to execute. Let's see the process to create one. First, we need to add some includes :

#include <NilkinsScripts/Scripts/Script.h> #include <NilkinsScripts/Scripts/ScriptManager.h>

Which allows us to manipulate the script :

nkScripts::Script* script = nkScripts::ScriptManager::getInstance()->createOrRetrieve("firstScript") ; script->setScriptFor(nkScripts::INTERPRETER::LUA) ;

We ask the ScriptManager to create the Script for us. Then, we prepare it to address a Lua Environment. Now, our script is ready to be setup :

script->setSources ( R"eos( s = 1 ; t = s + 5 ; print(t) ; )eos" ) ; // Triggers compilation of bytecode to use within the environment script->load() ;

First, we specify the sources. As we prepared our script and environment to be used with Lua, we need to write a Lua program. After that, we ask the script to load. This will compile the sources and make them available for an environment.

Final step to run the script : we need to ask the environment to execute it. Let's see :

env->execute(*script) ;

As simple as this : ask the environment to run a compiled script. Now, if we run the application, a nice "6" appears in the console, which is indeed the result of our operation on t, printed in the console.

And that's it for the basic setup. We are ready to write more complex sources, using the default Lua environment capabilities, or augment the environment to offer more capabilities through it.
One last point, before going through the next tutorial, would be to connect the logger to the component's LogManager. Let's include what we will need :

#include <NilkinsLog/ConsoleLogger.h>

Along with :

#include <NilkinsScripts/Log/LogManager.h>

And :

#include <memory>

Now, let's link all of them, before initializing our environment to potentially catch any error :

std::unique_ptr<nkLog::Logger> logger = std::make_unique<nkLog::ConsoleLogger>() ; nkScripts::LogManager::getInstance()->setReceiver(logger.get()) ;

We first create a console logger, and register it within the component's LogManager. Doing that will help when using the component, as all warnings, incorrect API calls and their reasons will be logged through the LogManager. For instance, if we forget to load our script and execute it anyway, we now witness in the console :

Error
The environment cannot run not compiled scripts

And this concludes the basic setup for a healthy nkScripts environment. For now, the only things we can do is address a vanilla Lua environment, but through the next tutorials, we will see how to make it spicier !